Release 10.1A: OpenEdge Development:
ADM and SmartObjects

Transaction-level validation procedures

As updates are made, the ADM creates a version of the RowObject temp-table, called RowObjUpd, that contains only the rows that are being updated (that is, modified, added, or deleted). It passes the RowObjUpd temp-table to the server side of the Commit process, which finds the corresponding database records (using the RowIdent field) and moves the update rows into those records. ADM allows you to implement transaction-level validation at various points in the process.

The SmartDataObject contains four entry points for transaction-level validation procedures: preTransactionValidate, beginTransactionValidate, endTransactionValidate, and postTransactionValidate. These entry points are simply procedure names that execute NO-ERROR. If you want your SmartDataObject to perform custom validation at a particular point in a transaction, you simply write an internal procedure of the corresponding name in the SmartDataObject. These procedures are executed where the database connection is. If the SmartDataObject is divided between client and AppServer, they are executed on the AppServer.

The four entry points operate as follows:

preTransactionValidate — This procedure is executed immediately before a transaction block begins. At this point, all rows in the RowObjUpd temp-table are available, can be read, and, if necessary, can be modified. This is the appropriate place to put checks that would result in canceling a transaction before it begins; for example, checks that verify the validity or consistency of rows being added, updated, or deleted. It also is the place to put code that changes or sets any values in those records that have not been set before; for example, totals.
beginTransactionValidate — This procedure is executed immediately after the beginning of a transaction block. This is the appropriate place for business logic that:
Updates related database records that should be updated as part of the same transaction.
Does not depend on SmartDataObject updates having been made to the database already.
endTransactionValidate — This procedure is executed immediately before the end of a transaction block. This is the appropriate place for:
Business logic that updates related database records that should be updated as part of the same transaction.
Performing other checks that are dependent on SmartDataObject updates having been made to the database already.

For example, if the logic for an Order SmartDataObject must total all orders to compare them with a credit limit, then it must be able to read not only updated order records but also any records already in the database. This logic is easier to implement if it is executed after the updated rows are written back to the database.

As another example, suppose you add to a SmartDataObject a row for which the following are true:

It is a one-to-one join of two database tables.
Its key field, which is the join field for the tables, is assigned from a numeric sequence in the database.

In this case, it is impossible to assign the key field value for the second table any sooner than at the end of the transaction. An endTransactionValidate procedure can read the primary table record from the database, retrieve the key value, and assign it to the secondary table record.

postTransactionValidate — This procedure is executed immediately after the end of the transaction block. This is the appropriate place to put business logic that performs other checks that should not be part of the basic transaction; for example, sending status messages or other work that should be performed in a separate transaction or in no transaction at all.

Each of these procedures has access to the RowObjUpd table and to any connected database tables. The procedures signal error by RETURNing an error message; if any of these procedures does return an error message, processing stops. Thus:

When preTransactionValidate returns an error, it cancels the update before the transaction begins.
When beginTransactionValidate or endTransactionValidate returns an error, it undoes the transaction.
When postTransactionValidate returns an error, there is no effect on the transaction: it does not undo the transaction because at that point, the transaction has already been completed.
Note: The version of ADM available in Progress V9.0 provided a single entry point called TransactionValidate for transaction-level validation. In subsequent releases, the preTransactionValidate procedure effectively replaces TransactionValidate, but TransactionValidate is still supported for backward compatibility. As is the case with preTransactionValidate, TransactionValidate executes NO-ERROR so it runs only if it was defined for the SmartDataObject.